home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 17 / CU Amiga Magazine's Super CD-ROM 17 (1997)(EMAP Images)(GB)[!][issue 1997-12].iso / CUCD / Programming / DiceSource / src / shared_lib / README < prev    next >
Encoding:
Text File  |  1993-04-18  |  6.8 KB  |  182 lines
  1.  
  2.             SHARED_LIB EXAMPLE CODE
  3.  
  4.     This is a fully compilable shared library implemented for DICE
  5.     demonstrating how one can write their very own shared library.  Some
  6.     knowledge in shared libraries is required to understand the code..
  7.     the basic thing to remember is (1) that a shared library is NOT a
  8.     normal C program, and (2) the interface calls MUST be reentrant...
  9.     i.e. multiple tasks can make a library call simultaniously.
  10.  
  11.     The only limitation with this example is that I use -mRR which turns on
  12.     registered arguments.  The limitation is that currently DICE will only
  13.     generated registered functions for those routines that take no more
  14.     than 2 integers and 2 pointers.  Routines that take more than that
  15.     limit or take other types (structures, floating pt, etc...) will
  16.     not have a registered entry point.
  17.  
  18.                 SHARED LIBRARY
  19.  
  20.     DEFS.H    contains header stuff
  21.     TAG.A    library independant basic code
  22.     LIB.C    library independant basic code
  23.     INIT.C    library dependant initialization routines
  24.     FUNCS.C    library dependant routines
  25.  
  26.     TAG.A and LIB.C are almost self contained with only a few modifications
  27.     required to use them for other library projects... basically the
  28.     name of the library in TAG.A and the function list in LIB.C
  29.  
  30.     TAG.A contains a subset of the standard startup code, LIB/AMIGA/C.A,
  31.     and assumes non-resident compilation (i.e. you cannot use the -r
  32.     option).  This isn't a problem since the -r option doesn't gain you
  33.     anything as far as shared libraries go.
  34.  
  35.     The individual library interface routines are declared with the LibCall
  36.     macro, defined in DEFS.H, which ensures the small-data pointer is set
  37.     up for all interface calls allowing use of the small-data model.
  38.  
  39.                 LIBRARY INTERFACE
  40.  
  41.     LIB.FD    The .FD file must match library prototypes.  The first two
  42.         integer arguments are stuck in D0 & D1 while the first
  43.         two pointer arguments are stuck in A0 & A1.
  44.  
  45.     AUTO.A    This is extremely DICE specific in that it gives programs
  46.         that link with the interface .lib (link library) the
  47.         capability to auto-open & close test.library without
  48.         having to explicitly do so in main().
  49.  
  50.         Notice that test.c doesn't explicitly OpenLibrary() or
  51.         CloseLibrary() "test.library".  DICE provides such
  52.         capabilities for most standard amiga libraries in the
  53.         same fashion.
  54.  
  55.     ---
  56.  
  57.     To compile, be sure that -2.0 is specified in your DCCOPTS an the
  58.     2.0 registered libraries are unpacked:
  59.  
  60.     DLIB:amigasr20.lib
  61.     DLIB:cr.lib
  62.  
  63.     DINCLUDE:AMIGA20/*/*.h
  64.  
  65.     Create a temporary directory to hold the resulting objects and the
  66.     resulting .lib tag library.  The resulting .library file will be placed
  67.     in LIBS: and the test program will be T:test
  68.  
  69.     DTMP:sharlib/        (to hold the objects & .lib file)
  70.  
  71.     Note that you will get warnings from FDTOLIB, these can be ignored. A
  72.     non-registered and registered version of the interface link library
  73.     required when linking TEST.C is generated, and two versions of TEST.C
  74.     are included to show what is required to compile either a normal
  75.     program or registered-args program that talks to the registered-args
  76.     library.
  77.  
  78.     1> dmake
  79.     ... compiles it all ...
  80.     1> test.script
  81.  
  82.  
  83.                 THE LINK LIB
  84.  
  85.     You will notice that the test program must be linked with test.lib
  86.     from DTMP:sharlib/ .. this is the library interface tag library
  87.     which interfaces C calls to a shared library.  Under DICE, a twist
  88.     is added in the form of a special auto-open module appended to the
  89.     .lib file.
  90.  
  91.     This auto-open module allows the TEST program to make library calls
  92.     without explicitly openning the shared library!  This greatly simplifies
  93.     the complication that using shared libraries generally adds.
  94.  
  95.     If you are interested, you should run 'DOBJ DTMP:SHARLIB/TEST.LIB' to
  96.     see how the link library works.
  97.  
  98.                ORDERING OF REGISTERED ARGUMENTS
  99.  
  100.     Arguments to registered calls work as follows:
  101.  
  102.     if (number of args <= 4 && not var-args-call && only int & ptr args)
  103.         put arguments in registers
  104.     else
  105.         use stack call
  106.  
  107.     Registers are assigned to arguments in argument order.  Integers are
  108.     assigned to D0 and D1 if available at the point they are scanned, else
  109.     A0 then A1 will be used (again, if not already assigned).  Pointers
  110.     are assigned to A0 and A1 if available at the point they are scanned,
  111.     else D0 then D1 will be used (again, if not already assigned to a
  112.     previous argument).
  113.  
  114.     (a few examples of register ordering)
  115.  
  116.     fubar(int, char *, int, char *)
  117.        D0    A0     D1    A1
  118.  
  119.     fubar(char *, int, char *, int)
  120.        A0      D0    A0    D0
  121.  
  122.     fubar(char *, int, int, int)
  123.         A0      D0   D1   A1
  124.  
  125.     fubar(int, int, int, char *)
  126.        D0  D1   A0      A1        <---- note!
  127.  
  128.     fubar(char *, char *, char *, int)
  129.         A0        A1       D0      D1    <---- note!
  130.  
  131.     You need to know the register ordering to construct your .FD file
  132.     properly.
  133.  
  134.  
  135.              NOT USING REGISTERED ARGUMENTS
  136.  
  137.     When you are not using registered arguments you will still want
  138.     the library to be called with arguments in registers.  However,
  139.     since your library routine does not use registered arguments you
  140.     will need to create an assembly tag in TAG.A to deal with it, then
  141.     have your function array in LIB.C point to the tags instead of the
  142.     actual library functions.
  143.  
  144.     Example:    if you have a routine called 'MyLibCall' in C, it's
  145.     symbol in assembly would be _MyLibCall.  The easiest thing to do
  146.     then is in lib.c change the MyLibCall function pointer to Asm_MyLibCall
  147.     and in assembly write the following:
  148.  
  149.             xdef    _Asm_MyLibCall    ; assembly tag
  150.             xref    _MyLibCall    ; C stack call
  151.  
  152.     _Asm_MyLibCall    movem.l  D0/D1,-(sp)     ; push registers
  153.             jsr    _MyLibCall(pc)
  154.             addq.l    #8,sp
  155.             rts
  156.  
  157.     Be extremely careful pushing registers, MOVEM always orders registers
  158.     being pushed D0..D7,A0..A7, you cannot specify the order in the MOVEM
  159.     call and may have to resort to several MOVE calls to accomplish your
  160.     task.  You do not have to restore the registers since only A2-A6/D2-D7
  161.     are required to be left alone, and the C function will do this
  162.     automatically, so in the example above I simply addq.l #8,sp to pop
  163.     the stack back up (if more than 8 bytes use lea XX(sp),sp).
  164.  
  165.     Complex libraries with complex calls may be easier to write if you
  166.     use assembly tags and not rely on registered arguments for the
  167.     library routines themselves.  Actually, the best way is to use
  168.     reg-args for those library calls that fit the requirements and
  169.     tags for those that do not, but this can be complicated and should
  170.     not be tried unless you are an experienced C programmer.
  171.  
  172.     -------------------------------------------------------------------
  173.  
  174.     version 1
  175.     Fixed bug in open if error occurs openning librariies... accidently
  176.     put garbage into A7 before returning.  Oops
  177.  
  178.     version 0
  179.     Initial release of example
  180.  
  181.  
  182.